<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>loscil</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="OpcodesTop.html" title="Orchestra Opcodes and Operators" />
    <link rel="prev" href="lorisplay.html" title="lorisplay" />
    <link rel="next" href="loscil3.html" title="loscil3" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">loscil</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="lorisplay.html">Prev</a> </td>
          <th width="60%" align="center">Orchestra Opcodes and Operators</th>
          <td width="20%" align="right"> <a accesskey="n" href="loscil3.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="refentry">
      <a id="loscil"></a>
      <div class="titlepage"></div>
      <a id="IndexLoscil" class="indexterm"></a>
      <div class="refnamediv">
        <h2>
          <span class="refentrytitle">loscil</span>
        </h2>
        <p>loscil — 
      Read sampled sound from a table.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp120661520"></a>
        <h2>Description</h2>
        <p>
      Read sampled sound (mono or stereo) from a table, with optional sustain and release looping.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp120662832"></a>
        <h2>Syntax</h2>
        <pre class="synopsis">ar1 [,ar2] <span class="command"><strong>loscil</strong></span> xamp, kcps, ifn [, ibas] [, imod1] [, ibeg1] [, iend1] \
      [, imod2] [, ibeg2] [, iend2]</pre>
      </div>
      <div class="refsect1">
        <a id="idp120665120"></a>
        <h2>Initialization</h2>
        <p>
      <span class="emphasis"><em>ifn</em></span> -- function table number, typically denoting an sampled sound segment with prescribed looping points loaded using <a class="link" href="GEN01.html" title="GEN01"><em class="citetitle">GEN01</em></a>. The source file may be mono or stereo.
    </p>
        <p>
      <span class="emphasis"><em>ibas</em></span> (optional) -- base frequency in <span class="emphasis"><em>Hz</em></span> of the recorded sound. This optionally overrides the frequency given in the audio file, but is required if the file did not contain one. The default value is 261.626 Hz, i.e. middle C. (New in Csound 4.03). If this value is not known or not present, use 1 here and in <span class="emphasis"><em>kcps</em></span>.
    </p>
        <p>
      <span class="emphasis"><em>imod1, imod2</em></span> (optional, default=-1) -- play modes for the sustain and release loops. A value of 1 denotes normal looping, 2 denotes forward &amp; backward looping, 0 denotes no looping. The default value (-1) will defer to the mode and the looping points given in the source file. Make sure you select an appropriate mode if the file does not contain this information.
    </p>
        <p>
      <span class="emphasis"><em>ibeg1, iend1, ibeg2, iend2</em></span> (optional, dependent on <span class="emphasis"><em>mod1, mod2</em></span>) -- begin and end points of the sustain and release loops. These are measured in <span class="emphasis"><em>sample frames</em></span> from the beginning of the file, so will look the same whether the sound segment is monaural or stereo. If no loop points are specified, and a looping mode (<span class="emphasis"><em>imod1</em></span>, <span class="emphasis"><em>imod2</em></span>) is given, the file will be looped for the whole length.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp120674416"></a>
        <h2>Performance</h2>
        <p>
      <span class="emphasis"><em>ar1, ar2</em></span> -- the output at audio-rate. There is just <span class="emphasis"><em>ar1</em></span> for mono output. However, there is both <span class="emphasis"><em>ar1</em></span> and <span class="emphasis"><em>ar2</em></span> for stereo output.
    </p>
        <p>
      <span class="emphasis"><em>xamp</em></span> -- the amplitude of the output signal.
    </p>
        <p>
      <span class="emphasis"><em>kcps</em></span> -- the frequency of the output signal in cycles per second.
    </p>
        <p>
      <span class="emphasis"><em>loscil</em></span> samples the ftable audio at a rate determined by <span class="emphasis"><em>kcps</em></span>, then multiplies the result by <span class="emphasis"><em>xamp</em></span>. The sampling increment for <span class="emphasis"><em>kcps</em></span> is dependent on the table's base-note frequency <span class="emphasis"><em>ibas</em></span>, and is automatically adjusted if the orchestra <span class="emphasis"><em>sr</em></span> value differs from that at which the source was recorded. In this unit, ftable is always sampled with interpolation.
    </p>
        <p>
      If sampling reaches the <span class="emphasis"><em>sustain loop</em></span> endpoint and looping is in effect, the point of sampling will be modified and <span class="emphasis"><em>loscil</em></span> will continue reading from within that loop segment. Once the instrument has received a <span class="emphasis"><em>turnoff</em></span> signal (from the score or from a MIDI noteoff event), the next sustain endpoint encountered will be ignored and sampling will continue towards the <span class="emphasis"><em>release loop</em></span> end-point, or towards the last sample (henceforth to zeros).
    </p>
        <p>
      <span class="emphasis"><em>loscil</em></span> is the basic unit for building a sampling synthesizer. Given a sufficient set of recorded piano tones, for example, this unit can resample them to simulate the missing tones. Locating the sound source nearest a desired pitch can be done via table lookup. Once a sampling instrument has begun, its <span class="emphasis"><em>turnoff</em></span> point may be unpredictable and require an external <span class="emphasis"><em>release</em></span> envelope; this is often done by gating the sampled audio with <a class="link" href="linenr.html" title="linenr"><em class="citetitle">linenr</em></a>, which will extend the duration of a turned-off instrument by a specific period while it implements a decay.
    </p>
        <p>
      If you want to loop the whole file, specify a looping mode in <span class="emphasis"><em>imod1</em></span> and do not enter any values for <span class="emphasis"><em>ibeg</em></span> and <span class="emphasis"><em>iend</em></span>.
    </p>
        <div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;">
          <table border="0" summary="Caution: Note to Windows users">
            <tr>
              <td rowspan="2" align="center" valign="top" width="25">
                <img alt="[Caution]" src="images/caution.png" />
              </td>
              <th align="left">Note to Windows users</th>
            </tr>
            <tr>
              <td align="left" valign="top">
                <p>
        Windows users typically use back-slashes, <span class="quote">“<span class="quote">\</span>”</span>, when specifying the paths of their files. As an example, a Windows user might use the path <span class="quote">“<span class="quote">c:\music\samples\loop001.wav</span>”</span>. This is problematic because back-slashes are normally used to specify special characters.
      </p>
                <p>
        To correctly specify this path in Csound, one may alternately:
        </p>
                <div class="itemizedlist">
                  <ul class="itemizedlist" style="list-style-type: disc; ">
                    <li class="listitem">
                      <p><span class="emphasis"><em>Use forward slashes</em></span>: c:/music/samples/loop001.wav</p>
                    </li>
                    <li class="listitem">
                      <p><span class="emphasis"><em>Use back-slash special characters, <span class="quote">“<span class="quote">\\</span>”</span></em></span>: c:\\music\\samples\\loop001.wav</p>
                    </li>
                  </ul>
                </div>
                <p>
      </p>
              </td>
            </tr>
          </table>
        </div>
        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <table border="0" summary="Note: Note">
            <tr>
              <td rowspan="2" align="center" valign="top" width="25">
                <img alt="[Note]" src="images/note.png" />
              </td>
              <th align="left">Note</th>
            </tr>
            <tr>
              <td align="left" valign="top">
                <p>
        This is mono <span class="emphasis"><em>loscil</em></span>:

        </p>
                <div class="informalexample">
                  <pre class="programlisting">
a1 <span class="opc">loscil</span> 10000, 1, 1, 1 ,1</pre>
                </div>
                <p>

        ...and this is stereo <span class="emphasis"><em>loscil</em></span>:

        </p>
                <div class="informalexample">
                  <pre class="programlisting">
a1, a2 <span class="opc">loscil</span> 10000, 1, 1, 1 ,1</pre>
                </div>
                <p>
      </p>
              </td>
            </tr>
          </table>
        </div>
      </div>
      <div class="refsect1">
        <a id="idp120700720"></a>
        <h2>Examples</h2>
        <p>
      Here is an example of the loscil opcode. It uses the files <a class="ulink" href="examples/loscil.csd" target="_top"><em class="citetitle">loscil.csd</em></a>, <a class="ulink" href="examples/mary.wav" target="_top"><em class="citetitle">mary.wav</em></a> and <a class="ulink" href="examples/kickroll.wav" target="_top"><em class="citetitle">kickroll.wav</em></a>.
      </p>
        <div class="example">
          <a id="idp120704240"></a>
          <p class="title">
            <strong>Example 444. Example of the loscil opcode.</strong>
          </p>
          <div class="example-contents">
            <p>See the sections <a class="link" href="UsingRealTime.html" title="Real-Time Audio"><em class="citetitle">Real-time Audio</em></a> and <a class="link" href="CommandFlags.html" title="Csound command line"><em class="citetitle">Command Line Flags</em></a> for more information on using command line flags.</p>
            <pre class="programlisting">
<span class="csdtag">&lt;CsoundSynthesizer&gt;</span>
<span class="csdtag">&lt;CsOptions&gt;</span>
<span class="comment">; Select audio/midi flags here according to platform</span>
-odac     <span class="comment">;;;realtime audio out</span>
<span class="comment">;-iadc    ;;;uncomment -iadc if realtime audio input is needed too</span>
<span class="comment">; For Non-realtime ouput leave only the line below:</span>
<span class="comment">; -o loscil.wav -W ;;; for file output any platform</span>
<span class="csdtag">&lt;/CsOptions&gt;</span>
<span class="csdtag">&lt;CsInstruments&gt;</span>

<span class="ohdr">sr</span> <span class="op">=</span> 44100
<span class="ohdr">ksmps</span> <span class="op">=</span> 32
<span class="ohdr">nchnls</span> <span class="op">=</span> 2
<span class="ohdr">0dbfs</span>  <span class="op">=</span> 1

<span class="oblock">instr</span> 1

ichnls <span class="op">=</span> <span class="opc">ftchnls</span>(p4)
<span class="opc">print</span> ichnls

<span class="octrl">if</span> (ichnls <span class="op">==</span> 1) then
   asigL <span class="opc">loscil</span> .8, 1, p4, 1
   asigR <span class="op">=</span> 	asigL
<span class="octrl">elseif</span> (ichnls <span class="op">==</span> 2) then
   asigL, asigR <span class="opc">loscil</span> .8, 1, p4, 1
<span class="comment">;safety precaution if not mono or stereo</span>
<span class="octrl">else</span>
   asigL <span class="op">=</span> 0
   asigR <span class="op">=</span> 0
<span class="octrl">endif</span>
        <span class="opc">outs</span> asigL, asigR

<span class="oblock">endin</span>
<span class="csdtag">&lt;/CsInstruments&gt;</span>
<span class="csdtag">&lt;CsScore&gt;</span>
<span class="stamnt">f</span> 1 0 0 1 "mary.wav" 0 0 0
<span class="stamnt">f</span> 2 0 0 1 "kickroll.wav" 0 0 0

<span class="stamnt">i</span> 1 0 3 1 <span class="comment">;mono file</span>
<span class="stamnt">i</span> 1 + 2 2 <span class="comment">;stereo file</span>
<span class="stamnt">e</span>
<span class="csdtag">&lt;/CsScore&gt;</span>
<span class="csdtag">&lt;/CsoundSynthesizer&gt;</span>
</pre>
          </div>
        </div>
        <p><br class="example-break" />
    </p>
      </div>
      <div class="refsect1">
        <a id="idp120708528"></a>
        <h2>See Also</h2>
        <p>
      <a class="link" href="loscil3.html" title="loscil3"><em class="citetitle">loscil3</em></a> and 
      <a class="link" href="GEN01.html" title="GEN01"><em class="citetitle">GEN01</em></a>
    </p>
      </div>
      <div class="refsect1">
        <a id="idp120711536"></a>
        <h2>Credits</h2>
        <p>Note about the mono/stereo difference was contributed by Rasmus Ekman.</p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="lorisplay.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="OpcodesTop.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="loscil3.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">lorisplay </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> loscil3</td>
        </tr>
      </table>
    </div>
  </body>
</html>
